packages/mg-beehiiv-api-members/README.md-1-3 (1)

1-3: ⚠️ Potential issue | 🟡 Minor

Replace the placeholder README before merge.

This package is set up for public consumption, but the README still has only .... Please add the auth requirements, CLI usage, expected outputs, and any Beehiiv limitations so consumers can use it without reading the source.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/README.md` around lines 1 - 3, Replace the
placeholder README in packages/mg-beehiiv-api-members/README.md with a complete
user-facing document: add an "Authentication" section that lists required env
vars or API token names and scopes, a "CLI usage" section with example commands
and required flags/arguments for the package's CLI entrypoint, an "Expected
outputs" section showing sample successful and error JSON responses from the key
functions (e.g., member create/list endpoints), and a "Beehiiv limitations"
section describing rate limits, pagination behavior, and any unsupported fields;
include short usage examples, exit codes, and troubleshooting tips so consumers
can use the package without reading the source.

packages/migrate/commands/beehiiv-api.js-16-16 (1)

16-16: ⚠️ Potential issue | 🟡 Minor

Fix misleading command description.

The description says "Migrate from beehiiv using CSV files" but this command uses the beehiiv API, not CSV files. The existing beehiiv command handles CSV-based migration.

📝 Proposed fix

-const desc = 'Migrate from beehiiv using CSV files';
+const desc = 'Migrate from beehiiv using the beehiiv API';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api.js` at line 16, Update the misleading
command description stored in the const desc in the beehiiv-api command so it
accurately reflects that this command migrates from Beehiiv via the Beehiiv API
(not CSV files); locate the const desc in
packages/migrate/commands/beehiiv-api.js and replace the current text 'Migrate
from beehiiv using CSV files' with a short, accurate description such as
'Migrate from Beehiiv using the Beehiiv API' or similar.

packages/migrate/commands/beehiiv-api.js-1-1 (1)

1-1: ⚠️ Potential issue | 🟡 Minor

Remove unused import.

The inspect import from node:util is not used anywhere in this file.

🧹 Proposed fix

-import {inspect} from 'node:util';
 import {ui} from '@tryghost/pretty-cli';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api.js` at line 1, The file imports inspect
from node:util but never uses it; remove the unused import statement "import
{inspect} from 'node:util';" (from the top of the module) and verify there are
no remaining references to inspect in functions like any helper or export in
this module so ESLint/TS will stop flagging an unused import.

packages/migrate/commands/beehiiv-api.js-147-150 (1)

147-150: ⚠️ Potential issue | 🟡 Minor

Remove dead code handling argv.url.

This code handles argv.url but there is no --url option defined in the options array. This code will never execute meaningfully.

🧹 Proposed fix

-    // Remove trailing slash from URL
-    if (argv.url && argv.url.endsWith('/')) {
-        argv.url = argv.url.slice(0, -1);
-    }
-
     // If no publication ID is provided, list publications and exit

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api.js` around lines 147 - 150, The
trailing-slash handling for argv.url is dead code because no --url option
exists; remove the entire conditional block that checks and slices argv.url (the
if (argv.url && argv.url.endsWith('/')) { argv.url = argv.url.slice(0, -1); })
from the migration command, or alternatively add a corresponding --url option to
the options array if the URL behavior was intended—pick one and implement
consistently so argv.url is never referenced without a defined option.

packages/migrate/commands/beehiiv-api-members.js-124-125 (1)

124-125: ⚠️ Potential issue | 🟡 Minor

Verbose logging points at a non-existent result field.

The members pipeline populates context.result.members, so inspect(context.result.data, ...) will just print undefined on success.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api-members.js` around lines 124 - 125, The
verbose log is printing context.result.data which is undefined because the
members pipeline puts results in context.result.members; update the ui.log.info
call (the block guarded by argv.verbose and context.result) to inspect and log
context.result.members (e.g., inspect(context.result.members, false, 2)) so the
actual member data is shown; ensure you reference ui.log.info, argv.verbose and
context.result.members when making the change and keep the existing null-check
on context.result or add a fallback if needed.

packages/migrate/commands/beehiiv-api-members.js-105-110 (1)

105-110: ⚠️ Potential issue | 🟡 Minor

Avoid raw console.table in the CLI command.

This currently fails the repo lint rule and bypasses the command's normal UI/logging path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api-members.js` around lines 105 - 110, The
CLI code uses raw console.table on getPubs which violates lint and bypasses the
command's logging/UI; replace the console.table call with the command's
logger/UI output (e.g., use the command context logger or existing
processLogger) and render the same rows by formatting getPubs.map(...) into a
string or using the repo's table helper before calling logger.info/log or the
command's print function; update the invocation around getPubs and the anonymous
map so it passes the formatted string to the logger instead of calling
console.table.

packages/mg-beehiiv-api-members/src/test/fetch.test.ts-179-182 (1)

179-182: ⚠️ Potential issue | 🟡 Minor

Mock discover() with the real publication payload.

fetchTasks() calls discover(), and discover() reads response.json().data.stats.active_subscriptions. These stubs return total_results instead, so estimatedPages becomes NaN and the pagination/progress path is never actually exercised.

Also applies to: 201-204, 245-248, 276-279, 309-312

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/test/fetch.test.ts` around lines 179 -
182, The mocked fetch responses used in the tests return an object shaped for
list endpoints ({ total_results }) but discover() expects the publication
payload and reads response.json().data.stats.active_subscriptions; update the
fetchMock.mock.mockImplementationOnce stubs used by tests that exercise
fetchTasks() (and indirectly discover()) to return a JSON shape matching the
real publication payload—i.e. response.json() should resolve to an object with a
data.stats.active_subscriptions numeric field (and any other fields discover()
needs such as has_more/page indicators) so estimatedPages is computed correctly;
apply the same change to the other test stubs referenced (the blocks at the
other locations listed) to ensure pagination/progress paths are exercised.

packages/mg-beehiiv-api/src/lib/process.ts-483-499 (1)

483-499: ⚠️ Potential issue | 🟡 Minor

Guard against undefined values to prevent runtime errors.

Several potential issues:

1. Line 486: firstImgSrc could be undefined (from attr('src')), causing .split() to throw.
2. Line 489: If URLs don't contain /uploads/asset/, split()[1] returns undefined, and undefined === undefined evaluates to true, potentially removing non-duplicate images.

Proposed fix with safety checks

-        // Both images usually end in the same way, so we can split the URL and compare the last part
-        const firstImageSplit = firstImgSrc.split('/uploads/asset/');
-        const featureImageSplit = featureSrc.split('/uploads/asset/');
-
-        if (firstImageSplit[1] === featureImageSplit[1]) {
-            $html(theElementItself).remove();
-        }
-
-        if (featureSrc.length > 0 && firstImgSrc) {
+        if (firstImgSrc && featureSrc) {
+            // Both images usually end in the same way, so we can split the URL and compare the last part
+            const firstImageSplit = firstImgSrc.split('/uploads/asset/');
+            const featureImageSplit = featureSrc.split('/uploads/asset/');
+
+            if (firstImageSplit[1] && featureImageSplit[1] && firstImageSplit[1] === featureImageSplit[1]) {
+                $html(theElementItself).remove();
+                return $html.html();
+            }
+
             let normalizedFirstSrc = firstImgSrc.replace('fit=scale-down,format=auto,onerror=redirect,quality=80', 'quality=100');
 
             if (featureSrc === normalizedFirstSrc) {
                 $html(theElementItself).remove();
             }
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/process.ts` around lines 483 - 499, Guard
against undefined and missing segments before splitting and comparing: ensure
firstImgSrc is truthy before calling split or replace, and verify both
firstImgSrc and featureSrc contain '/uploads/asset/' (or that split()[1] exists)
before comparing their [1] parts; also check featureSrc is non-empty before
normalizing and comparing to normalizedFirstSrc. Specifically, update the logic
around variables firstImgSrc, firstImageSplit, featureImageSplit and
normalizedFirstSrc in the block using $html(theElementItself) so you only call
.split(), .replace(), or access [1] when the source strings are defined and
include the expected substring, and bail out (skip removal) if those guards
fail.

packages/mg-beehiiv-api/tsconfig.json (2)

110-110: src/index.js in include is problematic.

Two issues with this entry:

1. The glob "src/**/*" already covers all files in src/, making "src/index.js" redundant if it's a TypeScript file.
2. If src/index.js is actually a JavaScript file, it won't be processed because allowJs is not enabled (line 48 is commented out).

If this package uses TypeScript throughout, remove the redundant entry. If there's genuinely a JS entry point, enable allowJs.

♻️ Suggested fix (assuming TypeScript only)

-  "include": ["src/**/*", "src/index.js"]
+  "include": ["src/**/*"]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/tsconfig.json` at line 110, The tsconfig's "include"
currently lists "src/**/*" and the redundant "src/index.js"; remove
"src/index.js" from the "include" array if the codebase is TypeScript-only (so
only "src/**/*" remains), otherwise if there truly is a JavaScript entry point
enable "allowJs": true (the commented out "allowJs" setting around line 48) so
the JS file will be picked up—apply the appropriate change in the tsconfig.json.

---

86-87: noImplicitAny is redundant with strict mode.

When strict: true is enabled, it implicitly enables noImplicitAny (among other strict checks). The explicit setting is harmless but unnecessary.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/tsconfig.json` around lines 86 - 87, The
tsconfig.json contains a redundant "noImplicitAny" entry because "strict": true
already enables it; remove the explicit "noImplicitAny" property (or
alternatively set it to identical value via a comment if you prefer
explicitness) so only "strict": true remains as the single source of truth for
strict checks; locate the JSON object containing the "strict" and
"noImplicitAny" keys and delete the "noImplicitAny" line.

packages/mg-beehiiv-api/src/lib/client.ts (1)

1-18: Avoid maintaining a second publications client here.

packages/mg-beehiiv-api/src/lib/list-pubs.ts already wraps the authenticated publications request on top of authedClient, and packages/mg-beehiiv-api/src/index.ts does not even export this client. Keeping both paths means the shipped code and the tested code can drift—they already differ on the expand[]=stats query parameter.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/client.ts` around lines 1 - 18, The file
defines a duplicate async function client that issues a GET to /publications;
instead of keeping this second publications client, remove or replace its usage
and delegate to the existing authedClient used by list-pubs.ts to avoid
divergence (ensure the same query params such as expand[]=stats are preserved).
Locate the client function in this file and either delete it or refactor callers
to call the shared authedClient wrapper (the same helper used by
packages/mg-beehiiv-api/src/lib/list-pubs.ts) so the exported surface matches
index.ts and the requests remain identical.

packages/mg-beehiiv-api-members/src/index.ts (1)

5-9: Consider using named exports for utilities.

Same feedback as for packages/mg-beehiiv-api/src/index.ts — these are utility functions that would be better served by named exports per coding guidelines.

♻️ Suggested refactor using named exports

 import {listPublications} from './lib/list-pubs.js';
 import {fetchTasks} from './lib/fetch.js';
 import {mapMembersTasks} from './lib/mapper.js';

-export default {
-    listPublications,
-    fetchTasks,
-    mapMembersTasks
-};
+export {
+    listPublications,
+    fetchTasks,
+    mapMembersTasks
+};

As per coding guidelines: "Named exports should be used for utilities, and default exports for main functionality (classes)."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/index.ts` around lines 5 - 9, Current
default export is exporting utility functions as a single default object; change
this to named exports by exporting listPublications, fetchTasks, and
mapMembersTasks individually (remove the default-exported object) so callers can
import them as named imports; update any internal references or import sites to
use the named imports if necessary (search for import of the default from this
module and switch to { listPublications, fetchTasks, mapMembersTasks }).

packages/mg-beehiiv-api/src/index.ts (1)

5-9: Consider using named exports for utilities.

Per coding guidelines, named exports should be used for utilities in index files, while default exports are reserved for main functionality (classes). Since listPublications, fetchTasks, and mapPostsTasks are utility functions, named exports would be more appropriate.

♻️ Suggested refactor using named exports

 import {listPublications} from './lib/list-pubs.js';
 import {mapPostsTasks} from './lib/mapper.js';
 import {fetchTasks} from './lib/fetch.js';

-export default {
-    listPublications,
-    fetchTasks,
-    mapPostsTasks
-};
+export {
+    listPublications,
+    fetchTasks,
+    mapPostsTasks
+};

Note: This would require updating consumers (e.g., packages/migrate/sources/beehiiv-api.js and packages/migrate/commands/beehiiv-api.js) to use named imports instead of default import.

As per coding guidelines: "Named exports should be used for utilities, and default exports for main functionality (classes)."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/index.ts` around lines 5 - 9, Replace the default
export object with named exports for the utility functions: export the functions
listPublications, fetchTasks, and mapPostsTasks as named exports (e.g., export {
listPublications, fetchTasks, mapPostsTasks }) and update any consumers (such as
migrate/sources/beehiiv-api.js and migrate/commands/beehiiv-api.js) to import
those functions by name instead of using the default import.

packages/mg-beehiiv-api-members/src/lib/list-pubs.ts (1)

9-11: Consider using @tryghost/errors for structured error handling.

Per coding guidelines, errors should use @tryghost/errors with message and context properties for better debugging and error tracking.

♻️ Suggested refactor using `@tryghost/errors`

+import errors from '@tryghost/errors';
 import {authedClient} from './fetch.js';

 const listPublications = async (apiKey: string) => {
     const url = new URL(`https://api.beehiiv.com/v2/publications`);
     url.searchParams.append('expand[]', 'stats');

     const response = await authedClient(apiKey, url);

     if (!response.ok) {
-        throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+        throw new errors.InternalServerError({
+            message: `Request failed: ${response.status} ${response.statusText}`,
+            context: {
+                url: url.toString(),
+                status: response.status,
+                statusText: response.statusText
+            }
+        });
     }

     const data = await response.json();

     return data.data;
 };

As per coding guidelines: "Use @tryghost/errors for structured error handling with message and context properties."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/lib/list-pubs.ts` around lines 9 - 11,
The current plain Error thrown when response.ok is false should be replaced with
an `@tryghost/errors` structured error: import errors from '@tryghost/errors' and
throw an instance that includes a descriptive message and a context object
(e.g., {status: response.status, statusText: response.statusText, url: <request
url or variable>}) in the list-pubs code path where response is checked; update
the code around response.ok in the listPubs (or the function that performs the
fetch) to construct and throw that `@tryghost/errors` error instead of new
Error(...) so logs and error handling get structured message and context.

packages/mg-beehiiv-api/src/lib/process.ts (2)

3-5: Remove unused imports.

sanitizeHtml (line 3) and imageCard (line 5) are imported but only referenced in commented-out code. Remove these to avoid confusion and dead imports.

Proposed fix

 import * as cheerio from 'cheerio';
 import _ from 'lodash';
-import sanitizeHtml from 'sanitize-html';
 import SimpleDom from 'simple-dom';
-import imageCard from '@tryghost/kg-default-cards/lib/cards/image.js';
 import embedCard from '@tryghost/kg-default-cards/lib/cards/embed.js';
 import bookmarkCard from '@tryghost/kg-default-cards/lib/cards/bookmark.js';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/process.ts` around lines 3 - 5, Remove the
dead imports sanitizeHtml and imageCard from the top of the file—keep only the
actually used SimpleDom import; update the import list in
packages/mg-beehiiv-api/src/lib/process.ts by deleting the sanitizeHtml and
imageCard import statements (they are only referenced in commented-out code) so
there are no unused imports left.

---

160-430: Remove or relocate commented-out code.

This block contains ~270 lines of commented-out code, which is a significant maintenance burden. If this code is experimental or for future use, consider:

1. Removing it entirely (it's preserved in version control history)
2. Moving it to a separate file or documentation if it serves as reference
3. Creating a tracking issue if it represents planned functionality

Keeping large blocks of dead code makes the file harder to read and maintain.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/process.ts` around lines 160 - 430, The large
~270-line commented block in process.ts (inside the HTML cleaning logic that
manipulates $html, options, postData, imageCard, embedCard, bookmarkCard,
serializer, getYouTubeID, etc.) should be removed or moved out of the file:
either delete it (history preserves it), extract it into a dedicated reference
file (e.g., a legacy or experimental helpers file) or add it to a design
doc/issue tracking planned features; update imports/usages if you relocate
helpers and ensure the active processing functions (the HTML-cleanup routine
surrounding $html and related handlers) remain clean and focused.

packages/migrate/commands/beehiiv-api-members.js (1)

96-115: ⚠️ Potential issue | 🟠 Major

Keep the no---id branch inside the try and return instead of hard-exiting.

mgBeehiivApiMembers.listPublications() still executes before the catch block, so discovery failures bypass ui.log.error(), and process.exit(0) short-circuits the normal command return path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api-members.js` around lines 96 - 115, Move
the "no --id" branch so that the call to
mgBeehiivApiMembers.listPublications(...) happens inside the existing try block
(so failures are caught by the catch), and replace process.exit(0) with a plain
return to allow the command to return normally; keep the same ui.log.error and
ui.log.warn messages but ensure any thrown errors from listPublications are
handled by the catch block rather than escaping it.

packages/mg-beehiiv-api/src/lib/mapper.ts (1)

11-13: ⚠️ Potential issue | 🟠 Major

Don't derive updated_at from created.

This makes every edited post look untouched after import. Map Beehiiv’s real update timestamp when it exists, or omit updated_at instead of copying the create time.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/mapper.ts` around lines 11 - 13, The mapping
currently sets updated_at from postData.created which hides edits; in mapper.ts
update the mapping for updated_at to use Beehiiv's real update timestamp when
present (e.g., check postData.updated, postData.updated_at, or whatever the API
field is) and convert it to a Date (new Date(postData.<updateField> * 1000)); if
no update timestamp exists, omit updated_at (or set it to undefined) instead of
copying created_at. Locate the mapping that sets published_at, updated_at,
created_at and replace the updated_at assignment accordingly.

packages/mg-beehiiv-api/src/lib/fetch.ts (1)

68-79: Date filtering is inefficient—runs on entire array each page.

The postsAfter and postsBefore filters re-process the entire accumulated ctx.result.posts array on every page fetch. Move these filters outside the pagination loop (after all pages are fetched) to avoid O(n²) behavior.

♻️ Suggested refactor

 export const fetchTasks = async (options: any, ctx: any) => {
     const numberOfPosts = await discover(options.key, options.id, API_LIMIT);
     const totalPages = Math.ceil(numberOfPosts / API_LIMIT);

     let tasks = [];

     for (let page = 1; page <= totalPages; page++) {
         tasks.push({
             title: `Fetching posts page ${page} of ${totalPages}`,
             task: async (_: any, task: any) => {
                 try {
                     let response = await cachedFetch({fileCache: ctx.fileCache ,key: options.key, pubId: options.id, page: page});

                     ctx.result.posts = ctx.result.posts.concat(response.data);
-
-                    if (options.postsAfter) {
-                        const afterTimestamp = new Date(options.postsAfter).getTime() / 1000;
-                        ctx.result.posts = ctx.result.posts.filter(
-                            (post: any) => post.publish_date >= afterTimestamp
-                        );
-                    }
-                    if (options.postsBefore) {
-                        const beforeTimestamp = new Date(options.postsBefore).getTime() / 1000;
-                        ctx.result.posts = ctx.result.posts.filter(
-                            (post: any) => post.publish_date <= beforeTimestamp
-                        );
-                    }
                 } catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
                     task.output = errorMessage;
                     throw error;
                 }
             }
         });
     }

+    // Add a final task to filter by date range
+    if (options.postsAfter || options.postsBefore) {
+        tasks.push({
+            title: 'Filtering posts by date range',
+            task: async () => {
+                if (options.postsAfter) {
+                    const afterTimestamp = new Date(options.postsAfter).getTime() / 1000;
+                    ctx.result.posts = ctx.result.posts.filter(
+                        (post: any) => post.publish_date >= afterTimestamp
+                    );
+                }
+                if (options.postsBefore) {
+                    const beforeTimestamp = new Date(options.postsBefore).getTime() / 1000;
+                    ctx.result.posts = ctx.result.posts.filter(
+                        (post: any) => post.publish_date <= beforeTimestamp
+                    );
+                }
+            }
+        });
+    }

     return tasks;
 };

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/fetch.ts` around lines 68 - 79, The date
filters (options.postsAfter and options.postsBefore) are currently applied to
ctx.result.posts inside the pagination loop, causing repeated full-array scans;
move the filtering logic out of the loop so you fetch and append all pages first
(the code that populates ctx.result.posts), then after pagination completes
apply a single filter pass using options.postsAfter and options.postsBefore
(convert to timestamps once, e.g. new Date(...).getTime()/1000) to produce the
final ctx.result.posts; update/remove the in-loop blocks that reference
ctx.result.posts.filter and ensure you only compare post.publish_date to the
computed afterTimestamp/beforeTimestamp once after all pages are aggregated.

packages/migrate/commands/beehiiv-api-members.js (1)

96-115: ⚠️ Potential issue | 🟠 Major

Keep the publication-listing branch inside the existing try and return normally.

listPublications(argv.key) still runs before the catch, so any rejection skips ui.log.error(). process.exit(0) also hard-stops the CLI in a path that can just return after printing the table and warning.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api-members.js` around lines 96 - 115, The
publication-listing branch currently calls
mgBeehiivApiMembers.listPublications(argv.key) outside the try/catch and calls
process.exit(0); move the entire block (the listPublications call, the getPubs
check, console.table, and ui.log.warn) inside the same try that wraps the
migration logic so any rejection is caught by the existing catch, and replace
process.exit(0) with a plain return so the CLI returns normally after printing
the table and warning; ensure you keep the ui.log.error usage in the catch to
log API rejections.

packages/migrate/sources/beehiiv-api.js (1)

68-68: ⚠️ Potential issue | 🟠 Major

Normalize every ctx.errors.push(...) to one structured payload.

These catches still push (message, error) while Line 56 pushes an object, so ctx.errors ends up heterogeneous. Any downstream consumer expecting a consistent {message, error} shape will mis-handle part of the pipeline's failures.

Suggested fix

-                    ctx.errors.push('Failed to process beehiiv content', error);
+                    ctx.errors.push({message: 'Failed to process beehiiv content', error});

-                    ctx.errors.push('Failed to build link map', error);
+                    ctx.errors.push({message: 'Failed to build link map', error});

-                    ctx.errors.push('Failed to format data as Ghost JSON', error);
+                    ctx.errors.push({message: 'Failed to format data as Ghost JSON', error});

-                    ctx.errors.push('Failed to convert HTML -> Lexical', error);
+                    ctx.errors.push({message: 'Failed to convert HTML -> Lexical', error});

-                    ctx.errors.push('Failed to write Ghost import JSON File', error);
+                    ctx.errors.push({message: 'Failed to write Ghost import JSON File', error});

-                    ctx.errors.push('Failed to write and upload ZIP file', error);
+                    ctx.errors.push({message: 'Failed to write and upload ZIP file', error});

-                    ctx.errors.push('Failed to clear temporary cached files', error);
+                    ctx.errors.push({message: 'Failed to clear temporary cached files', error});

As per coding guidelines, "**/*.{ts,js}: Use @tryghost/errors for structured error handling with message and context properties."

Also applies to: 80-80, 92-92, 126-126, 138-138, 170-170, 182-182

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/sources/beehiiv-api.js` at line 68, The ctx.errors array is
getting heterogeneous entries because some catches call ctx.errors.push('Failed
to process beehiiv content', error) while others push an object; update every
ctx.errors.push call in this file (e.g., the pushes that use the literal message
'Failed to process beehiiv content' and the occurrences at the mentioned
locations) to push a single structured payload with consistent shape — use
`@tryghost/errors` to create a structured error (include message and
context/details) or wrap into an object like {message: 'Failed to process
beehiiv content', error: /* original error */} so all entries written by
ctx.errors.push share the same {message, error} (or {message, context})
structure.

packages/mg-beehiiv-api-members/src/lib/fetch.ts (1)

28-34: Consider replacing any types with proper interfaces.

Using any for fileCache, options, and ctx loses type safety. Based on context snippet 3, these have known structures that could be typed.

Also applies to: 63-63

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/lib/fetch.ts` around lines 28 - 34,
Replace the loose any types by declaring and using explicit interfaces for the
cache and surrounding call shapes: define a FileCache interface
(methods/properties used by cachedFetch), an Options interface for the `options`
object, and a Context (ctx) interface matching what's used elsewhere, then
update the cachedFetch signature to use FileCache instead of any and replace
other occurrences (e.g., the `options` and `ctx` parameters referenced around
symbol names `options` and `ctx`) to use those interfaces; ensure
exported/locally-scoped types match the fields observed in the surrounding code
so TypeScript can enforce correct usage.

packages/mg-beehiiv-api-members/src/lib/list-pubs.ts (1)

13-15: Consider adding return type annotation and null safety.

The function returns data.data without type validation. If the API response structure changes or data.data is undefined, this could cause runtime issues downstream. The caller in beehiiv-api-members.js (lines 101-109) accesses properties like pub.name, pub.id, pub.created, and pub.stats?.active_subscriptions.

🛡️ Proposed type-safe return

-    const data = await response.json();
-
-    return data.data;
+    const data = await response.json();
+
+    return data.data ?? [];

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/lib/list-pubs.ts` around lines 13 - 15,
The code returns data.data without type safety; update the function in
list-pubs.ts (e.g., listPubs) to declare an explicit return type (for example
Promise<Pub[]>), define a Pub interface including id, name, created and optional
stats.active_subscriptions, and validate the parsed JSON before returning: check
that response.ok, that data is an object and Array.isArray(data.data), and
either return data.data as Pub[] after a runtime guard or return an empty array
/ throw a descriptive error if the shape is invalid so callers (which access
pub.name, pub.id, pub.created, pub.stats?.active_subscriptions) won't encounter
undefined properties. Ensure you use type assertions only after the runtime
checks.

packages/mg-beehiiv-api-members/src/test/mapper.test.ts (2)

336-351: Make the Error-path test deterministic.

packages/mg-beehiiv-api-members/src/lib/mapper.ts:89-95 explicitly copies error.message into task.output, but this test currently relies on an incidental TypeError from invalid input and only checks for a non-empty string. That makes the contract easy to regress without failing the test.

💡 Suggested change

         it('task sets error output on failure with Error instance', async () => {
-            const ctx = {
+            const ctx: any = {
                 result: {
-                    subscriptions: 'not an array' // Invalid data
+                    get subscriptions() {
+                        throw new Error('Custom error');
+                    }
                 }
             };
 
             const tasks = mapMembersTasks({}, ctx);
             const mockTask = {output: ''};
@@
             await assert.rejects(async () => {
                 await tasks[0].task({}, mockTask);
             });
 
-            assert.ok(mockTask.output.length > 0);
+            assert.equal(mockTask.output, 'Custom error');
         });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/test/mapper.test.ts` around lines 336 -
351, The test should deterministically verify that the task copies the thrown
Error.message into task.output: call mapMembersTasks to get tasks, invoke
tasks[0].task and capture the rejected Error (e.g. via try/catch or .catch(err
=> ...)), then assert that mockTask.output === err.message (instead of only
checking mockTask.output.length > 0); reference mapMembersTasks and
mockTask.output to locate the change and replace the assert.rejects + length
check with an assertion that output equals the captured error.message.

---

353-371: Remove the synthetic raw string throw test case.

This test disables no-throw-literal and models an error shape the codebase explicitly discourages per coding guidelines ("Use @tryghost/errors for structured error handling with message and context properties"). No source code in the Beehiiv packages throws raw values—only test files do so with explicit linting disables. Keep the failure-path coverage on Error or @tryghost/errors instances instead.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api-members/src/test/mapper.test.ts` around lines 353 -
371, Remove the synthetic raw string throw test "task sets error output on
failure with non-Error thrown" and replace it with a failure-path test that
throws an actual Error (or an instance of `@tryghost/errors`) so it conforms to
project error-handling guidelines; locate the test in mapper.test.ts that
constructs ctx.result.get subscriptions throwing 'Custom string error' and
either delete that block or change the thrown value to new Error('Custom string
error') (or a `@tryghost/errors` instance) and assert mockTask.output is set
accordingly when invoking mapMembersTasks and executing tasks[0].task.

packages/mg-beehiiv-api/src/lib/fetch.ts (1)

68-79: Move date filtering outside the pagination loop.

The date filters are applied to the entire ctx.result.posts array on every page iteration, which is inefficient. Posts from earlier pages are re-filtered unnecessarily.

♻️ Proposed fix - filter once after all pages are fetched

Move filtering to after the loop completes, or apply it to fetchTasks caller:

-                    if (options.postsAfter) {
-                        const afterTimestamp = new Date(options.postsAfter).getTime() / 1000;
-                        ctx.result.posts = ctx.result.posts.filter(
-                            (post: any) => post.publish_date >= afterTimestamp
-                        );
-                    }
-                    if (options.postsBefore) {
-                        const beforeTimestamp = new Date(options.postsBefore).getTime() / 1000;
-                        ctx.result.posts = ctx.result.posts.filter(
-                            (post: any) => post.publish_date <= beforeTimestamp
-                        );
-                    }
                 } catch (error) {

Then add a final task or post-processing step to apply filtering once.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/fetch.ts` around lines 68 - 79, The date
filtering for options.postsAfter/options.postsBefore is being applied to
ctx.result.posts inside the pagination loop (causing repeated re-filtering);
move the filter logic out of the loop and apply it once after all pages are
fetched (e.g., after the fetch/pagination loop in fetchTasks or as a final
post-processing step) so that ctx.result.posts is filtered a single time using
new Date(options.postsAfter).getTime()/1000 and new
Date(options.postsBefore).getTime()/1000 on the final aggregate array.

packages/mg-beehiiv-api/src/lib/process.ts (1)

205-475: Remove or address the extensive commented-out code.

There are ~270 lines of commented-out code. This creates maintenance burden and confusion. Consider:

1. Removing it if no longer needed
2. Moving to a separate branch/issue if it's WIP
3. Adding a TODO comment explaining why it's kept if intentional

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/process.ts` around lines 205 - 475, The file
contains ~270 lines of large commented-out transformation logic (many $html(...)
blocks including image handling, embedCard.render, imageCard.render,
bookmarkCard.render, YouTube handling and options?.url branches) which should be
cleaned up; either delete these commented sections if obsolete, move them to a
dedicated WIP branch or a new file (e.g., archive the legacy html-to-ghost
conversion helpers), or replace the block with a short TODO comment explaining
why the code is retained and linking to an issue/branch/PR; update references
around the functions/constructs mentioned ($html, imageCard.render,
embedCard.render, bookmarkCard.render, getYouTubeID, options?.url) so callers
are clear and ensure any tests or docs note where the archived logic lives.

packages/mg-beehiiv-api/src/lib/client.ts (1)

1-22: Consider consolidating with authedClient in fetch.ts.

This client function duplicates the authenticated fetch pattern already implemented by authedClient in fetch.ts (see context snippet). The only difference is this hardcodes the publications URL. Consider either:

1. Reusing authedClient here, or
2. Removing this file and using listPublications from list-pubs.ts which already does this

♻️ Proposed consolidation

+import {authedClient} from './fetch.js';
+
 const client = async (apiKey: string) => {
     const url = new URL(`https://api.beehiiv.com/v2/publications`);
-
-    const response = await fetch(url, {
-        method: 'GET',
-        headers: {
-            Authorization: `Bearer ${apiKey}`
-        }
-    });
+    const response = await authedClient(apiKey, url);
 
     if (!response.ok) {
         throw new Error(`Request failed: ${response.status} ${response.statusText}`);
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/client.ts` around lines 1 - 22, The client
function in client.ts duplicates the authenticated fetch pattern implemented by
authedClient (fetch.ts) and/or the listPublications helper (list-pubs.ts);
refactor by either replacing client to call authedClient with the publications
path and the provided apiKey (so client delegates URL construction and error
handling to authedClient) or delete client.ts and update callers to use
listPublications from list-pubs.ts; references to change: client (in client.ts),
authedClient (in fetch.ts), and listPublications (in list-pubs.ts).

packages/mg-beehiiv-api/src/test/fetch.test.ts (2)

23-27: Assert the auth header via Headers, not object shape.

RequestInit.headers is not guaranteed to be a plain object. This assertion will fail on a valid implementation that passes a Headers instance or tuple array.

Suggested change

             assert.equal(fetchMock.mock.callCount(), 1);
             const [calledUrl, options] = fetchMock.mock.calls[0].arguments;
             assert.equal(calledUrl.toString(), 'https://api.beehiiv.com/v2/publications');
             assert.equal(options.method, 'GET');
-            assert.equal(options.headers.Authorization, 'Bearer test-api-key');
+            assert.equal(new Headers(options.headers).get('Authorization'), 'Bearer test-api-key');

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/test/fetch.test.ts` around lines 23 - 27, The
test currently asserts options.headers as a plain object which fails when
implementations supply a Headers instance; update the assertion to normalize and
read the Authorization header via the Headers API (e.g., construct a Headers
from RequestInit.headers or call .get on it) using the existing variables
fetchMock.mock.calls, calledUrl and options; ensure you assert that new
Headers(options.headers).get('Authorization') equals 'Bearer test-api-key' and
keep the URL and method assertions as-is.

---

91-116: Add one cache-path filter test.

The suite verifies caching and date filtering separately, but not together. If the cached branch ever bypasses postsAfter/postsBefore, these tests would still stay green.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/test/fetch.test.ts` around lines 91 - 116, The
test is missing coverage that cached responses are still subject to the same
date/path filters; update or add a test that calls fetchTasks with filtering
options (e.g., postsAfter/postsBefore or the cache-path filter param used by
fetchTasks) and a ctx.fileCache that returns cachedData via readTmpJSONFile,
then run tasks[0].task and assert the cached posts are filtered (only expected
items remain) and that fetchMock was only called once (discover); reference
fetchTasks, tasks[0].task, ctx.fileCache.readTmpJSONFile, and the
postsAfter/postsBefore (or cache-path) filter parameters when implementing the
test.

packages/migrate/sources/beehiiv-api.js (1)

1-1: Replace synchronous file I/O with async variant in upload path.

readFileSync() blocks the event loop, and await readFileSync() does not perform asynchronous I/O—the file read completes synchronously before await wraps it in a Promise. For large export ZIPs, this will stall the task runner immediately before upload.

Suggested fix

-import {readFileSync} from 'node:fs';
+import {readFile} from 'node:fs/promises';
...
-                        const fileBuffer = await readFileSync(ctx.outputFile.path);
+                        const fileBuffer = await readFile(ctx.outputFile.path);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/sources/beehiiv-api.js` at line 1, The code currently
imports and uses readFileSync which performs blocking I/O; replace readFileSync
with an async file-read (e.g., use readFile from 'node:fs/promises' or import {
readFile } from 'node:fs' and use the promises API) and await the promise in the
upload path so the event loop is not blocked before the upload; update the
import (remove readFileSync) and change the code that reads the export ZIP (the
place using readFileSync) to call and await the async read function before
passing the buffer to the upload routine.

packages/mg-beehiiv-api/src/lib/client.ts (1)

13-15: ⚠️ Potential issue | 🟠 Major

Add request metadata to the thrown Ghost error.

This still throws a structured error without any request context, which makes API failures much harder to diagnose downstream. Include at least status, statusText, and url in context.

🧩 Suggested change

     if (!response.ok) {
-        throw new errors.InternalServerError({message: `Request failed: ${response.status} ${response.statusText}`});
+        throw new errors.InternalServerError({
+            message: `Request failed: ${response.status} ${response.statusText}`,
+            context: {
+                status: response.status,
+                statusText: response.statusText,
+                url: url.toString()
+            }
+        });
     }

As per coding guidelines, "Use @tryghost/errors for structured error handling with message and context properties."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/client.ts` around lines 13 - 15, The thrown
structured error in the response handling (errors.InternalServerError) lacks
request metadata; update the throw inside the response.ok check in client.ts to
pass a context object containing at least response.status, response.statusText,
and response.url (e.g., include properties status, statusText, url on the
error's context) so downstream handlers get request details; keep using
errors.InternalServerError but supply the additional context argument alongside
the message.

packages/migrate/commands/beehiiv-api-members.js (1)

101-115: ⚠️ Potential issue | 🟠 Major

Return from run() instead of terminating the process.

After printing the publication table you can just return. listPublications() either returns an array or throws, so getPubs?.errors is dead, and process.exit(0) makes this command harder to reuse and test.

🧩 Suggested change

             if (!getPubs || !getPubs.length) {
-                ui.log.error('Error fetching publications:', getPubs?.errors || 'No publications found');
+                ui.log.error('No publications found');
                 return;
             }
@@
             ui.log.warn('No publication ID provided. Please provide an ID using the --id flag to run the migration.');
-
-            process.exit(0);
+            return;
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api-members.js` around lines 101 - 115, The
code in run() treats getPubs as possibly containing an errors property and calls
process.exit(0) after logging the publications; instead, remove the dead
getPubs?.errors check (listPublications() either returns an array or throws),
change the error handling to rely on the thrown error or an empty-array check,
and replace process.exit(0) with a simple return so listPublications() and the
publication listing in run() (and the ui.log.error/ui.log.warn calls) are
testable and the command is reusable.

packages/mg-beehiiv-api/src/test/fetch.test.ts (1)

158-162: ⚠️ Potential issue | 🟡 Minor

Mock fetch failures as rejected promises.

Real fetch() failures reject the promise instead of throwing synchronously, so this case is not exercising the same async path as production code.

🧩 Suggested change

-            fetchMock.mock.mockImplementationOnce(() => {
-                // eslint-disable-next-line no-throw-literal
-                throw 'Network error string';
-            }, 1);
+            fetchMock.mock.mockImplementationOnce(() => Promise.reject('Network error string'), 1);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/test/fetch.test.ts` around lines 158 - 162, The
test currently simulates a fetch failure by throwing a string in
fetchMock.mock.mockImplementationOnce, which doesn't match real fetch behavior;
change that mock to return a rejected promise instead (e.g., have
fetchMock.mock.mockImplementationOnce(() => Promise.reject('Network error
string'), 1)) so the async rejection path exercised in the production code is
used; update any assertions if they expect an Error object to instead handle the
rejected value or wrap it in an Error as appropriate.

packages/mg-beehiiv-api/src/lib/fetch.ts (1)

20-21: ⚠️ Potential issue | 🟠 Major

Preserve request identifiers in the HTTP failures.

Both error paths drop metadata that is already in scope, so once these bubble through the task runner it's hard to tell which publication or page failed. Put the request details into context at each throw site.

As per coding guidelines, "Use @tryghost/errors for structured error handling with message and context properties."

Also applies to: 44-45

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/lib/fetch.ts` around lines 20 - 21, The throw
sites in this module (the InternalServerError thrown when response.ok is false
and the similar throw around lines 44-45) drop useful metadata; update both
error constructions to pass a context object with the request identifiers
already in scope (e.g., requestId, publicationId, pageId, url, method or
whatever request metadata variables exist) so the error uses
errors.InternalServerError({message: "...", context: { ... }}). Locate the two
throw sites (the current throw that uses response.status/response.statusText and
the other throw at 44-45) and add the appropriate context property populated
from the local request/metadata variables in this file so the task runner can
trace which publication/page failed.

packages/migrate/commands/beehiiv-api.js (1)

149-163: ⚠️ Potential issue | 🟠 Major

Handle the empty discovery path without touching .errors or exiting the process.

listPublications() returns an array or throws, so getPubs.errors is not a valid fallback here. In the falsy case it can also throw a secondary TypeError, and process.exit(0) is unnecessary once the table has been shown.

🧩 Suggested change

             if (!getPubs || !getPubs.length) {
-                ui.log.error('Error fetching publications:', getPubs.errors);
+                ui.log.error('No publications found');
                 return;
             }
@@
             ui.log.warn('No publication ID provided. Please provide an ID using the --id flag to run the migration.');
-
-            process.exit(0);
+            return;
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/migrate/commands/beehiiv-api.js` around lines 149 - 163, The check
for publications uses getPubs.errors and forcibly exits the process; fix by
treating listPublications() as returning an array (or throwing) — remove any
access to getPubs.errors and do not call process.exit(0). Specifically, in the
code around listPublications/getPubs and the UI logging, replace the falsy
branch to simply log a warning via ui.log.warn or ui.log.info when getPubs is
empty (e.g., if (!getPubs || getPubs.length === 0) { ui.log.warn('No
publications found'); return; }) and ensure any thrown errors from
listPublications() are handled by a surrounding try/catch that logs the caught
error via ui.log.error. Also remove the unconditional process.exit(0) after the
console.table so the caller can continue.

packages/mg-beehiiv-api/src/types.d.ts (1)

9-77: ⚠️ Potential issue | 🟠 Major

Make these declaration aliases module-scoped.

beehiivPostDataObject, tagsObject, authorsObject, and mappedDataObject are ambient globals right now, so sibling modules can consume them without import type. That creates collision risk and makes the type surface brittle; export the aliases (or move the bare declare module ... shims into a separate .d.ts) and import them explicitly where they’re used.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/mg-beehiiv-api/src/types.d.ts` around lines 9 - 77, The types
beehiivPostDataObject, tagsObject, authorsObject, and mappedDataObject are
currently declared as ambient globals; change them to module-scoped exports so
other modules must import them. Update the declarations by exporting each type
(e.g., export type beehiivPostDataObject = { ... }) or wrap them in a module and
export, and then replace any usage sites to import type { beehiivPostDataObject,
tagsObject, authorsObject, mappedDataObject } from the file where you move them;
alternatively move these bare shims into a dedicated .d.ts that explicitly
exports them to avoid global collisions.